I3DExShader Struct Reference
[External Interfaces]

Inheritance diagram for I3DExShader:

List of all members.

Public Member Functions
virtual boolean MCCOMAPI	IsEqualTo (I3DExShader *aShader)=0
virtual MCCOMErr MCCOMAPI	GetShadingFlags (ShadingFlags &theFlags)=0
virtual boolean MCCOMAPI	WantsTransform ()=0
virtual EShaderOutput MCCOMAPI	GetImplementedOutput ()=0
virtual boolean MCCOMAPI	HasExplicitLightingModel (const LightingContext &lightingContext)=0
virtual MCCOMErr MCCOMAPI	ShadeAndLight (LightingDetail &result, const LightingContext &lightingContext, I3DShLightingModel *inDefaultLightingModel)=0
virtual MCCOMErr MCCOMAPI	DoShade (ShadingOut &result, ShadingIn &shadingIn)=0
virtual real MCCOMAPI	GetValue (real &result, boolean &fullArea, ShadingIn &shadingIn)=0
virtual real MCCOMAPI	GetColor (TMCColorRGBA &result, boolean &fullArea, ShadingIn &shadingIn)=0
virtual void MCCOMAPI	GetReflection (TReflectionParameters &reflectionParams, const ShadingIn &shadingIn)=0
virtual void MCCOMAPI	GetTransparency (TTransparencyParameters &transparencyParams, const ShadingIn &shadingIn)=0
virtual real MCCOMAPI	GetVector (TVector3 &result, ShadingIn &shadingIn)=0
virtual MCCOMErr MCCOMAPI	GetBump (TVector3 &result, ShadingIn &shadingIn)=0
virtual void MCCOMAPI	ConvertToPoly (TMCArray< TVector2 > *vertices)=0
virtual boolean MCCOMAPI	OutlineInPreviewMode ()=0
virtual boolean MCCOMAPI	Contains (ShadingIn &shadingIn, TVector2 &localUV)=0
virtual MCCOMErr MCCOMAPI	GetOriginalParametricTextureMap (const uint32 &uvSpaceID, const uint32 &channelIndex, IShTextureMap **outMap)=0
virtual boolean MCCOMAPI	GetSubShaderPreview (IShParameterComponent **shader, IShParameterComponent *subShader, FourCharT subShaderKeyword)=0
virtual void MCCOMAPI	GetShaderPreview (IShParameterComponent **shader)=0
virtual int16 MCCOMAPI	GetSubShaderViewID (IDType keyword)=0
virtual MCCOMErr MCCOMAPI	SetDefaultParameters ()=0
virtual EShaderFunctionType MCCOMAPI	GetSubShaderType (IDType keyword)=0
virtual void MCCOMAPI	CalculateDirectLighting (LightingDetail &result, const LightingContext &lightingContext)=0
virtual void MCCOMAPI	CalculateReflection (TMCColorRGB &reflectionColor, const LightingContext &lightingContext, const ShadingOut &shading)=0
virtual void MCCOMAPI	CalculateCaustics (TMCColorRGB &causticColor, const LightingContext &lightingContext, const ShadingOut &shading)=0
virtual void MCCOMAPI	CalculateIndirectLighting (TMCColorRGB &indirectDiffuseColor, const LightingContext &lightingContext, const ShadingOut &shading)=0
virtual void MCCOMAPI	CalculateTransparency (TMCColorRGBA &resColor, const LightingContext &lightingContext, const ShadingOut &shading)=0
virtual void MCCOMAPI	CalculateAlpha (TMCColorRGBA &resColor, const LightingContext &lightingContext, const ShadingOut &shading)=0
virtual void MCCOMAPI	CalculateSubsurfaceScattering (TMCColorRGB &subsurfaceColor, const LightingContext &lightingContext, const ShadingOut &shading)=0

---

Detailed Description

Shaders are used to give photorealistic appearance to an object’s surface. They define a value for each point in the UV space of an object. They are used by the renderer to calculate the appearance of an object in the rendered image. A shader is comprised of a group of channels (color, transparency, reflections, etc.) which are combined to form a complete shader.

Shaders are designed to be re-entrant such that the output from one shader can be used as the input for another shader. This is accomplished by implementing methods to return a value, color, or complete shading structure and then using GetShadingFlags() and GetImplementedOutput() to define which implementation was used. Methods that return simply a value, color, or vector use the "ShadingIn" struct, filling in the fields as defined by GetShadingFlags() independent of the channel in which the shader is placed. A shader that implements an entire shading structure uses a "ShadingOut" structure that sets values for a ShadingIn structure for each channel of the shader.

Lighting Model: shaders can override the default lighting model to provide a more accurate definition of the surface properties. This allows to simulate effects such as anisotropic material or glass with fresnel effect. You could also use a shader to implement a global illumination effect that only applies to certain objects.

Note: When implementing a shader with sub-shaders in their PMap, the shaders ID must have a specific name to be properly copied when the shader parent is replaced by another shader accepting sub-shaders.( replacement is done in TComponentTreePart::RetrieveComponent ) Complex shaders ( Operators, Mixers, Curve Editor, Color Gradient ) use the following norm: 'Sh00', 'Sh01', 'Sh02', ... for naming their shaders in the PMap.

---

Member Function Documentation

virtual void MCCOMAPI I3DExShader::CalculateAlpha (  TMCColorRGBA &  resColor, const LightingContext &  lightingContext, const ShadingOut &  shading )  [pure virtual]

Override this method to implement your own Alpha channel calculation. Note that if you have overriden ShadeAndLight(), this method won't be called. Parameters: resColor  The resulting color. lightingContext  Info about the point being shaded and the lighting of the scene. shading  The shading at this point. Implemented in TBasicShader.

virtual void MCCOMAPI I3DExShader::CalculateCaustics (  TMCColorRGB &  causticColor, const LightingContext &  lightingContext, const ShadingOut &  shading )  [pure virtual]

Override this method to implement your own Caustics calculation. Note that if you have overriden ShadeAndLight(), this method won't be called. Parameters: causticColor  The resulting caustic color. lightingContext  Info about the point being shaded and the lighting of the scene. shading  The shading at this point. Implemented in TBasicShader.

virtual void MCCOMAPI I3DExShader::CalculateDirectLighting (  LightingDetail &  result, const LightingContext &  lightingContext )  [pure virtual]

Override this method to implement your own direct lighting calculation. Note that if you have overriden ShadeAndLight(), this method won't be called. Parameters: result  The result direct lighting lightingContext  Info about the point being shaded and the lighting of the scene. Implemented in TBasicShader.

virtual void MCCOMAPI I3DExShader::CalculateIndirectLighting (  TMCColorRGB &  indirectDiffuseColor, const LightingContext &  lightingContext, const ShadingOut &  shading )  [pure virtual]

Override this method to implement your own Global Illumination calculation. Note that if you have overriden ShadeAndLight(), this method won't be called. Parameters: indirectDiffuseColor  The resulting indirect lighting color. lightingContext  Info about the point being shaded and the lighting of the scene. shading  The shading at this point. Implemented in TBasicShader.

virtual void MCCOMAPI I3DExShader::CalculateReflection (  TMCColorRGB &  reflectionColor, const LightingContext &  lightingContext, const ShadingOut &  shading )  [pure virtual]

Override this method to implement your own reflection calculation. Note that if you have overriden ShadeAndLight(), this method won't be called. Parameters: reflectionColor  The resulting reflection color. lightingContext  Info about the point being shaded and the lighting of the scene. shading  The shading at this point. Implemented in TBasicShader.

virtual void MCCOMAPI I3DExShader::CalculateSubsurfaceScattering (  TMCColorRGB &  subsurfaceColor, const LightingContext &  lightingContext, const ShadingOut &  shading )  [pure virtual]

Override this method to implement your own Subsurface Scattering calculation. Note that if you have overriden ShadeAndLight(), this method won't be called. Parameters: subsurfaceColor  The resulting subsurface scattering color. lightingContext  Info about the point being shaded and the lighting of the scene. shading  The shading at this point. Implemented in TBasicShader.

virtual void MCCOMAPI I3DExShader::CalculateTransparency (  TMCColorRGBA &  resColor, const LightingContext &  lightingContext, const ShadingOut &  shading )  [pure virtual]

Override this method to implement your own Transparency calculation. Note that if you have overriden ShadeAndLight(), this method won't be called. Parameters: resColor  The resulting transparency color. lightingContext  Info about the point being shaded and the lighting of the scene. shading  The shading at this point. Implemented in TBasicShader.

virtual boolean MCCOMAPI I3DExShader::Contains (  ShadingIn &  shadingIn, TVector2 &  localUV )  [pure virtual]

Returns true if a point in uv coordinates is contained in the shape of the shaders (used for shape shaders only). Parameters: shadingIn  The information about the point being shaded. localUV  The uv in the current projection mapping. Implemented in TBasicShader.

virtual void MCCOMAPI I3DExShader::ConvertToPoly (  TMCArray< TVector2 > *  vertices  )  [pure virtual]

must be implemented to allow a shader to display an outline. This is typically used by layers such as ’rectangle’, ’ellipse’, and ’polygon’ Parameters: vertices  An array of 2D vertices used to draw a layout around the layer. Those vertices' coordinates are in the UVSpace of the layer. Implemented in TBasicShader.

virtual MCCOMErr MCCOMAPI I3DExShader::DoShade (  ShadingOut &  result, ShadingIn &  shadingIn )  [pure virtual]

Returns the shading at a given point as described in the shadingIn. Note that you also need to fill the fCurrentCompletionMask of shadingIn with the channels that your shader is actually filling (this allows to have shaders that only after certain channel without modifying the others in a layered shader). Note that the alpha is not premultiplied in the shading. Note: A shader should implement at least one other following methods: DoShader , GetValue or GetColor Parameters: result,:  the shading data as calculated by the shader shadingIn,:  the location where the shading should be calculated Returns: MC_S_OK if the shader implements this method, MC_E_NOTIMPL otherwise Implemented in TBasicShader.

virtual MCCOMErr MCCOMAPI I3DExShader::GetBump (  TVector3 &  result, ShadingIn &  shadingIn )  [pure virtual]

not supported in current version Implemented in TBasicShader.

virtual real MCCOMAPI I3DExShader::GetColor (  TMCColorRGBA &  result, boolean &  fullArea, ShadingIn &  shadingIn )  [pure virtual]

Calculates the color of a shader for given point described in shadingIn. Note that the alpha is not premultiplied in the shading ! (But it is in the lighting calculation) Parameters: result,:  The color of the point fullArea  Return false if the shader only did a point sampling, Return false if the shader average the shading over the area. shadingIn,:  the parameters for the shading Returns: The opacity (for Layer Lists) of this shader (between 0 and 1) Implemented in TBasicShader.

virtual EShaderOutput MCCOMAPI I3DExShader::GetImplementedOutput (   )  [pure virtual]

Determines which methods the Shader actually implements. Return only one of the following values if you implement only one of the methods. If more than one is implemented then return the result as the OR of the two values return kUsesGetValue | kUsesGetColor; For a complete description of the constant that can be used, please refer to EShaderOutput Implemented in TBasicShader.

virtual MCCOMErr MCCOMAPI I3DExShader::GetOriginalParametricTextureMap (  const uint32 &  uvSpaceID, const uint32 &  channelIndex, IShTextureMap **  outMap )  [pure virtual]

Returns the original texture map when no special projections mappings. Parameters: uvSpaceID  The uvSpaceID for which we want the texture channelIndex  The index of the channel that we want (color,alpha,...) outMap  Returns a pointer to the texture map if there is one. Implemented in TBasicShader.

virtual void MCCOMAPI I3DExShader::GetReflection (  TReflectionParameters &  reflectionParams, const ShadingIn &  shadingIn )  [pure virtual]

Returns the parameters used to calculate the reflection. This function is only called if the shader is placed in the reflection channel of a multichannel. Do not forget to specify kUseGetReflection in GetImplementedOutput(). Parameters: reflectionParams  The parameters used for reflections calculations shadingIn  The info about the point to shade Implemented in TBasicShader.

virtual void MCCOMAPI I3DExShader::GetShaderPreview (  IShParameterComponent **  shader  )  [pure virtual]

Creates a shader that can be used to preview this shader. Parameters: shader  Shader created to be used for the preview (this shader must be a clone). Implemented in TBasicShader.

virtual MCCOMErr MCCOMAPI I3DExShader::GetShadingFlags (  ShadingFlags &  theFlags  )  [pure virtual]

specifies which parameters the shader will need to perform shading calculations. If the shader is a constant shader which values does not depend on any of the ShadingIn parameters then it should set the fCallOnce flag in theFlags to true. See the description of the ShadingFlags structure for more details. Parameters: theFlags  The flags that are returned Implemented in TBasicShader.

virtual boolean MCCOMAPI I3DExShader::GetSubShaderPreview (  IShParameterComponent **  shader, IShParameterComponent *  subShader, FourCharT  subShaderKeyword )  [pure virtual]

Creates a shader that can be used to preview one of the subshader. Parameters: shader  Shader created to be used for the preview. subShader  Shader to put in the sub shader identified by the keyword subShaderKeyword. subShaderKeyword  Keywork of the sub shader (in the PMap). Returns: true if the shader created have to be processed by the parent shader, false if not. Implemented in TBasicShader.

virtual EShaderFunctionType MCCOMAPI I3DExShader::GetSubShaderType (  IDType  keyword  )  [pure virtual]

Get the type of a sub shader. Parameters: keyword  Id of the sub shader. Returns: the type of the sub shader. Implemented in TBasicShader.

virtual int16 MCCOMAPI I3DExShader::GetSubShaderViewID (  IDType  keyword  )  [pure virtual]

Get the view id of a sub shader. Parameters: keyword  Id of the sub shader. Returns: the view id (ressource id) of the view, or -1 if no view. Implemented in TBasicShader.

virtual void MCCOMAPI I3DExShader::GetTransparency (  TTransparencyParameters &  transparencyParams, const ShadingIn &  shadingIn )  [pure virtual]

Returns the parameters used to calculate the transparency. This function is only called if the shader is placed in the transparency channel of a multichannel. Parameters: transparencyParams  The parameters used for transparency calculations shadingIn  The info about the point to shade Implemented in TBasicShader.

virtual real MCCOMAPI I3DExShader::GetValue (  real &  result, boolean &  fullArea, ShadingIn &  shadingIn )  [pure virtual]

Calculates the value of the shader at a given point described in shadingIn. Note: A shader should implement at least one other following methods: DoShader , GetValue or GetColor Parameters: result  The resulting value fullArea  Return false if the shader only did a point sampling, Return false if the shader average the shading over the area. shadingIn,:  the parameters for the shading Returns: the opacity (for Layer Lists) of this shader (between 0 and 1) Implemented in TBasicShader.

virtual real MCCOMAPI I3DExShader::GetVector (  TVector3 &  result, ShadingIn &  shadingIn )  [pure virtual]

Returns a perturbation of the normal in local coordinates. This perturbation is then added to the orginal normal of the point to calculate the bump. Parameters: result,:  the perturbation of the normal shadingIn,:  the parameters for the shading Returns: The opacity (for Layer Lists) of this shader (between 0 and 1) Implemented in TBasicShader.

virtual boolean MCCOMAPI I3DExShader::HasExplicitLightingModel (  const LightingContext &  lightingContext  )  [pure virtual]

Returns true if there is an explicit lighting model in the subtree. This is mostly used for layer lists to determine if DoShade or ShadeAndLight should be called on the layer. Parameters: lightingContext  The information about the current point being shaded (including incoming ray...) Implemented in TBasicShader.

virtual boolean MCCOMAPI I3DExShader::IsEqualTo (  I3DExShader *  aShader  )  [pure virtual]

Compares the values of two shaders. IsEqualTo() must first get a pointer on the same interface as itself before comparing the values. Parameters: aShader  The shader that should be compared to this. Implemented in TBasicShader.

virtual boolean MCCOMAPI I3DExShader::OutlineInPreviewMode (   )  [pure virtual]

Return True if the shader will draw an outline. ConvertToPoly() must then be implemented. This is typically used by layers such as ’rectangle’, ’ellipse’, and ’polygon’ Implemented in TBasicShader.

virtual MCCOMErr MCCOMAPI I3DExShader::SetDefaultParameters (   )  [pure virtual]

Set the parameters to the default values (especially to create default sub shaders). Implemented in TBasicShader.

virtual MCCOMErr MCCOMAPI I3DExShader::ShadeAndLight (  LightingDetail &  result, const LightingContext &  lightingContext, I3DShLightingModel *  inDefaultLightingModel )  [pure virtual]

Calculates the shading and lighting in one point. You should only override this method if you want to implement advanced lighting effects in your shader. Note that you can override part of the lighting model by overriding CalculateDirectLighting() or CalculateReflection(),,, Parameters: result  The lighting that is returned. lightingContext  Info about the point being shaded and the lighting of the scene. inDefaultLightingModel  A pointer to the default lighting model. Returns: MC_S_OK if you implemented this method, MC_E_NOTIMPL if not. Implemented in TBasicShader.

virtual boolean MCCOMAPI I3DExShader::WantsTransform (   )  [pure virtual]

Returns true if the shader needs a transform tab. This is only useful if your shader relies on 3D coodinates and not UV coordinates. Implemented in TBasicShader.

---

The documentation for this struct was generated from the following file:

• I3dExShader.h

---